home *** CD-ROM | disk | FTP | other *** search
/ Aminet 24 / Aminet 24 (1998)(GTI - Schatztruhe)[!][Apr 1998].iso / Aminet / util / conv / Raw2Ent19.lha / Raw2Ent.doc < prev    next >
Text File  |  1998-01-19  |  25KB  |  723 lines
  1. Project: Raw2Ent
  2. ARexx  : Raw2Ent.rexx
  3. Version: 1.4.1 (14.07.96)
  4. Program: Raw2Ent
  5. Version: 1.9 (18.01.98)
  6. Author : Tamio Patrick Honma
  7.  
  8. Files  : Raw2Ent
  9.          Raw2Ent.ced
  10.          Raw2Ent.doc
  11.          Raw2Ent.dok
  12.          Raw2Ent.rexx
  13.          Raw2Ent.rexx.old
  14.          Raw2EntCheck
  15.          Raw2EntHTMLColors.iff
  16.          Raw2EntLogic.asc
  17.          Raw2EntMeta.asc
  18.          Raw2EntTables.doc
  19.          Raw2EntUml.r2e
  20.  
  21.  
  22. CONTENTS:
  23.  
  24. 1. INTRODUCTION
  25. 1.1. REQUIREMENTS
  26. 1.2. TECHNICAL INFORMATION
  27. 1.3. USER KNOWLEDGE
  28.  
  29. 2. USAGE
  30. 2.1. Raw2Ent VER: 1.9 (18.01.98)
  31. 2.2. Raw2Ent.ced VER: 1.01 (26.12.96)
  32. 2.3. Raw2Ent.rexx VER: 1.4.1 (14.07.96)
  33. 2.4. Raw2EntCheck VER: 1.0 (12.12.96)
  34. 2.5. ARGUMENT-PRIORITY
  35.  
  36. 3. LIMITATIONS
  37.  
  38. 4. INSTALLATION
  39.  
  40. 5. EXAMPLES
  41.  
  42. 6. BYE!
  43.  
  44. 7. LAST COMMENT
  45.  
  46. 8. BUG REPORTS
  47.  
  48. 9. HISTORY
  49.  
  50. 10.SUPPORT & MS-DOS-VERSION
  51.  
  52.  
  53.  
  54.  
  55. 1. INTRODUCTION
  56.  
  57. Raw2Ent   converts   raw   8-Bit-ASCII-Text   into   7-Bit-ASCII-Text   with
  58. entity-codes  and  reverse.   The  ASCII-Format is a standardized format for
  59. information  interchange,  but it is only standardized seven-bit-wide, which
  60. means  that  128 codes are defined.  One Byte consists of eight bits and can
  61. represent  256  different  bit  combinations.   Therefore  the  last 128 bit
  62. combinations  are defined for free use by any operation-system.  The problem
  63. is that accent-characters and other special characters are not standardized,
  64. because  they  are defined in (guess where?!  ;) ) the free part of ASCII by
  65. the operation system developers.
  66.  
  67. The  goal of the Wold Wide Web developers was that it could be used on every
  68. important   operation   system.   So  it  was  clear  that  the  ASCII-Based
  69. HTML-Source-Code   had  to  use  the  standardized  seven-bit  area  of  the
  70. ASCII-Code.  To represent accent-characters or other special characters in a
  71. seven-bit-code,  it  was  neccesary  to  invent something.  And this was the
  72. entity-code  -  a  kind  of  escape-code.   An  entity-code  consists  of an
  73. introducing  "&"  and  a  ";"  at  the  end.   Between  these  symbols  is a
  74. character-name the browser can interpret.  It is a very hard and stupid work
  75. to convert the ASCII-Text by hand.  So just use Raw2Ent!
  76.  
  77. Raw2Ent  produces  real 7-Bit-ASCII-Code.  All printable Amiga-characters in
  78. the  8-bit-area  will be converted into entity-codes, without any exception.
  79. The  use  of names instead of code-numbers will make the entity-codes easier
  80. to be read by humans.
  81.  
  82. You  can use Raw2Ent also to check, wether your file contains pure seven-bit
  83. codes  or  not.   If  not,  Raw2Ent  will  present  you  the position of the
  84. 8-Bit-Characters in the text.
  85.  
  86. Raw2Ent can also handle color-codes and -names.
  87.  
  88.  
  89. 1.1. REQUIREMENTS
  90.  
  91. - AmigaOS 2.0 or greater
  92. - optional: ARexx
  93. - optional: Cygnus ED
  94.  
  95.  
  96. 1.2. TECHNICAL INFORMATION (Raw2Ent)
  97.  
  98. +-----------+--------------------------+--------------+--------------+
  99. | Libraries | Code                     | OS-VERSION   | Bytes        |
  100. +-----------+--------------------------+--------------+--------------+
  101. | exec      | program-counter-relative | 36 or higher |  1250 Stack  |
  102. | dos       | MC 68000 CPU             |              | 11076 File   |
  103. |           | not yet re-entrant!      |              | 13072 Memory |
  104. |           |                          |              |     + Datas  |
  105. +-----------+--------------------------+--------------+--------------+
  106.  
  107.  
  108. 1.3. USER KNOWLEDGE
  109.  
  110. Raw2Ent:
  111. - AmigaOS Knowledge: CLI-commands, -arguments and standard-output.
  112. - American Standardisation Commitee for Information Interchange (ASCII)
  113. - "Bit", "Byte" -> 7Bit-ASCII, 8Bit-ASCII [i.e.: Amiga-ASCII]
  114. - Hypertext Markup Language (HTML) & Character-Entity-Codes & Color-Codes
  115. - Edit text with an ASCII-Editor
  116.  
  117. Raw2Ent.rexx:
  118. - How to start and use ARexx-Scripts
  119. - ... see Raw2Ent
  120.  
  121. Raw2Ent.ced:
  122. - How to use CygnusED and how to implement CED-Scripts
  123. - How to use ARexx
  124.  
  125. Raw2EntCheck:
  126. - How to use batch-files with AmigaOS
  127. - ... see Raw2Ent
  128.  
  129.  
  130. 2. USAGE
  131.  
  132. Raw2Ent  consists  of  four parts:  one assembler-program, two ARexx-Scripts
  133. and one Batch-File.
  134.  
  135. If   you   just   want   to   convert   a  text  once,  you  just  need  the
  136. assembler-program.   If  you  want  to  convert  one text more than one time
  137. because  you work on a project, like a web-page with actual information, the
  138. ARexx-Script may be useful.
  139.  
  140. Raw2Ent can be used with Cygnus ED.
  141.  
  142. Raw2Ent will create a backup-file, if Raw2Ent overwrites another file.  This
  143. feature can be switched off by using the switch "NOBAK" or "NOBACKUP".
  144.  
  145. If  you  want  to  append  one  file to another use the AmigaDOS-convention.
  146. Please   note,  that  the  "BACKUP"-Feature  will  take  no  effect  to  the
  147. destination file!
  148.  
  149. You  can  use  the  RETURNBYTE-option to implement the Check-Mode of Raw2Ent
  150. into editors like Cygnus ED.
  151.  
  152.  
  153. 2.1. Raw2Ent VER: 1.9 (18.01.98)
  154.  
  155. arguments:
  156.  
  157.   FROM                  - The source-file (eight bit wide)
  158.   TO                    - The destination-file (with entity-codes)
  159.                           [path without filename is not accepted]
  160.   DATA/K                - definition-file
  161.   ENT/S                 - default mode
  162.   TAG/S                 - activates the TAG-Mode
  163.   SMART/S               - activates the smart-mode
  164.   COPY=HTML/S           - activates the HTML-Mode
  165.   UML=NOENT/S           - removes high-bit characters by characters or words
  166.   CODE/S                - converts all entity-codes by code-number
  167.                           (except the four special entities)
  168.   TOTALCODE/S           - converts ALL characters by entity-code-numbers
  169.   INVERSE=ENT2RAW/S     - inverses the function of Raw2Ent to Ent2Raw
  170.   CHECK/S               - checks, if your Text is pure 7-Bit-ASCII
  171.   COLCODE=COLORCODE/S   - converts color-names to color-codes
  172.   COLHTML=COLORHTML/S   - converts color-codes to HTML-Color-Names
  173.   COLORNETSCAPE/S       - converts color-codes to NETSCAPE-Color-Names
  174.   LISTENT=LISTENTITY/S  - lists the Entity-Table
  175.   LISTUML=LISTUMLAUT/S  - lists the Umlaut-Table
  176.   LISTCOL=LISTCOLOR/S   - lists the Color-Table (HTML 3.2)
  177.   LISTNET=LISTNETSCAPE/S- lists the Netscape-Color-Table (without HTML 3.2)
  178.   NOBAK=NOBACKUP/S      - switches the backup feature off
  179.   RETBYTE=RETURNBYTE/S  - returns byte-position as return-code in check-mode
  180.  
  181.  
  182. modes:
  183.  
  184.  
  185. >DATA-Mode<
  186.  
  187. loads  one  definition-file  and uses this file as the convertion-table.  If
  188. you  want  to  define  one  table  on  your  own,  you  have  to  follow the
  189. instructions very strictly!
  190.  
  191. Edit the datafile with an ASCII-Editor like that:
  192.  
  193. (8 Bit-character)=(expression)<LINE-FEED>
  194. (8 Bit-character)=(expression)<LINE-FEED>
  195. etc.
  196. #<LINE-FEED>
  197.  
  198. EXAMPLE:
  199.  
  200. ©=Copyright in 
  201. ®=Produced on 
  202. ¶=<P>
  203. #
  204.  
  205. NOTE: YOU MUST STRICTLY FOLLOW THIS INSTRUCTION.
  206.       THIS MEANS:
  207.       - The 8-Bit character must be in the first column
  208.       - The "=" character must be in the second column
  209.       - The expression is free and must end with a line feed
  210.       - no empty lines allowed
  211.       - at the end of the definition must be an "#" in one line
  212.  
  213.       ALL UNDEFINED 8-BIT-CHARACTERS WILL BE REPRESENTED BY <NULL>
  214.  
  215.  
  216. >ENT-Mode<
  217.  
  218. is the default mode and converts every known character into its entity-code.
  219.  
  220.  
  221. >TAG-Mode<
  222.  
  223. will  not  convert  the  four  characters:   &  <  > ".  This is usefull for
  224. ASCII-Text  which  already  contains  entity-codes  or  HTML-TAGS, which are
  225. introduced  and  ended  by  "<"  and  ">" and which can contain quotes.  The
  226. "&"-character  usually introduces the entity-codes.  If you use the TAG-Mode
  227. the entity-codes in the source-file will not be converted a second time in a
  228. wrong  way,  but  untouched special-characters will be converted.  Therefore
  229. you should use this mode, whenever you convert a text a second time.
  230.  
  231.  
  232. >SMART-Mode<
  233.  
  234. is  a  combination  of  the  >ENT<-Mode  and the >TAG<-Mode.  HTML-Files for
  235. example   will   be   converted   without   destruction   of  HTML-Tags  and
  236. character-entity-codes  -  like  the >TAG<-Mode.  The difference is that the
  237. characters:   <  >  &  "  will  be  converted, if Raw2Ent "thinks" that this
  238. characters are no elements of the character-entity-codes or HTML-Tags.  This
  239. works the best, if the HTML-File contains "good" code.  I cannot guarantee a
  240. correct  interpreatation  by  Raw2Ent,  but  I  think  it